home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / jack / jack.h next >
C/C++ Source or Header  |  2005-12-20  |  25KB  |  734 lines
  1. /*
  2.     Copyright (C) 2001 Paul Davis
  3.     
  4.     This program is free software; you can redistribute it and/or modify
  5.     it under the terms of the GNU Lesser General Public License as published by
  6.     the Free Software Foundation; either version 2.1 of the License, or
  7.     (at your option) any later version.
  8.     
  9.     This program is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12.     GNU Lesser General Public License for more details.
  13.     
  14.     You should have received a copy of the GNU Lesser General Public License
  15.     along with this program; if not, write to the Free Software 
  16.     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  17.  
  18.     $Id: jack.h,v 1.64 2004/07/15 03:07:28 trutkin Exp $
  19. */
  20.  
  21. #ifndef __jack_h__
  22. #define __jack_h__
  23.  
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. #include <pthread.h>
  29.  
  30. #include <jack/types.h>
  31. #include <jack/transport.h>
  32.  
  33. /**
  34.  * Note: More documentation can be found in jack/types.h.
  35.  */
  36.  
  37. /**
  38.  * Attempt to become an external client of the Jack server.
  39.  *
  40.  * JACK is evolving a mechanism for automatically starting the server
  41.  * when needed.  As a transition, jack_client_new() only does this
  42.  * when $JACK_START_SERVER is defined in the environment of the
  43.  * calling process.  In the future this will become normal behavior.
  44.  * In either case, defining $JACK_NO_START_SERVER disables this
  45.  * feature.
  46.  *
  47.  * @param client_name of at most jack_client_name_size() characters.
  48.  *
  49.  * @return Opaque client handle if successful, otherwise NULL.
  50.  *
  51.  * @note Failure generally means that the JACK server is not running.
  52.  * If there was some other problem, it will be reported via the @ref
  53.  * jack_error_callback mechanism.
  54.  */
  55. jack_client_t *jack_client_new (const char *client_name);
  56.  
  57. /**
  58.  * Disconnects an external client from a JACK server.
  59.  *
  60.  * @return 0 on success, otherwise a non-zero error code
  61.  */
  62. int jack_client_close (jack_client_t *client);
  63.  
  64. /**
  65.  * @return the maximum number of characters in a JACK client name
  66.  * including the final NULL character.  This value is a constant.
  67.  */
  68. int jack_client_name_size(void);
  69.  
  70. /**
  71.  * Attempt to load an internal client into the Jack server.
  72.  *
  73.  * Internal clients run within the JACK server process.  They can use
  74.  * of the same functions as external clients.  Each internal client
  75.  * must declare jack_initialize() and jack_finish() entry points,
  76.  * called at load and unload times.  See inprocess.c for an example of
  77.  * how to write an internal client.
  78.  *
  79.  * @param client_name of at most jack_client_name_size() characters.
  80.  * @param so_name A path to a shared object file containing the code
  81.  * for the new client.
  82.  * @param so_data An arbitary string containing information to be
  83.  * passed to the jack_initialize() routine of the new client.
  84.  */
  85. int jack_internal_client_new (const char *client_name, const char *so_name,
  86.                   const char *so_data);
  87.  
  88. /**
  89.  * Removes an internal client from a JACK server.
  90.  *
  91.  * @return 0 on success, otherwise a non-zero error code
  92.  */
  93. void jack_internal_client_close (const char *client_name);
  94.  
  95. /**
  96.  * @param client pointer to JACK client structure.
  97.  *
  98.  * Check if the JACK subsystem is running with -R (--realtime).
  99.  *
  100.  * @return 1 if JACK is running realtime, 0 otherwise
  101.  */
  102. int jack_is_realtime (jack_client_t *client);
  103.  
  104. /** 
  105.  * @param client pointer to JACK client structure.
  106.  * @param function The jack_shutdown function pointer.
  107.  * @param arg The arguments for the jack_shutdown function.
  108.  *
  109.  * Register a function (and argument) to be called if and when the
  110.  * JACK server shuts down the client thread.  The function must
  111.  * be written as if it were an asynchonrous POSIX signal
  112.  * handler --- use only async-safe functions, and remember that it
  113.  * is executed from another thread.  A typical function might
  114.  * set a flag or write to a pipe so that the rest of the
  115.  * application knows that the JACK client thread has shut
  116.  * down.
  117.  *
  118.  * NOTE: clients do not need to call this.  It exists only
  119.  * to help more complex clients understand what is going
  120.  * on.  It should be called before jack_client_activate().
  121.  */
  122. void jack_on_shutdown (jack_client_t *client, void (*function)(void *arg), void *arg);
  123.  
  124. /**
  125.  * Tell the Jack server to call @a process_callback whenever there is
  126.  * work be done, passing @a arg as the second argument.
  127.  *
  128.  * The code in the supplied function must be suitable for real-time
  129.  * execution.  That means that it cannot call functions that might
  130.  * block for a long time.á This includes malloc, free, printf,
  131.  * pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
  132.  * pthread_cond_wait, etc, etc.á See
  133.  * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
  134.  * for more information.
  135.  *
  136.  * @return 0 on success, otherwise a non-zero error code, causing JACK
  137.  * to remove that client from the process() graph.
  138.  */
  139. int jack_set_process_callback (jack_client_t *client,
  140.                    JackProcessCallback process_callback,
  141.                    void *arg);
  142.  
  143. /**
  144.  * Tell JACK to call @a thread_init_callback once just after
  145.  * the creation of the thread in which all other callbacks 
  146.  * will be handled.
  147.  *
  148.  * The code in the supplied function does not need to be
  149.  * suitable for real-time execution.
  150.  *
  151.  * @return 0 on success, otherwise a non-zero error code, causing JACK
  152.  * to remove that client from the process() graph.
  153.  */
  154. int jack_set_thread_init_callback (jack_client_t *client,
  155.                    JackThreadInitCallback thread_init_callback,
  156.                    void *arg);
  157.  
  158. /**
  159.  * Tell the Jack server to call @a freewheel_callback
  160.  * whenever we enter or leave "freewheel" mode, passing @a
  161.  * arg as the second argument. The first argument to the
  162.  * callback will be non-zero if JACK is entering freewheel
  163.  * mode, and zero otherwise.
  164.  *
  165.  * @return 0 on success, otherwise a non-zero error code.
  166.  */
  167. int jack_set_freewheel_callback (jack_client_t *client,
  168.                  JackFreewheelCallback freewheel_callback,
  169.                  void *arg);
  170.  
  171. /**
  172.  * Start/Stop JACK's "freewheel" mode.
  173.  *
  174.  * When in "freewheel" mode, JACK no longer waits for
  175.  * any external event to begin the start of the next process
  176.  * cycle. 
  177.  *
  178.  * As a result, freewheel mode causes "faster than realtime"
  179.  * execution of a JACK graph. If possessed, real-time
  180.  * scheduling is dropped when entering freewheel mode, and
  181.  * if appropriate it is reacquired when stopping.
  182.  * 
  183.  * @param client pointer to JACK client structure
  184.  * @param onoff  if non-zero, freewheel mode starts. Otherwise
  185.  *                  freewheel mode ends.
  186.  *
  187.  * @return 0 on success, otherwise a non-zero error code.
  188.  */
  189. int jack_set_freewheel(jack_client_t* client, int onoff);
  190.  
  191. /**
  192.  * Change the buffer size passed to the @a process_callback.
  193.  *
  194.  * This operation stops the JACK engine process cycle, then calls all
  195.  * registered @a bufsize_callback functions before restarting the
  196.  * process cycle.  This will cause a gap in the audio flow, so it
  197.  * should only be done at appropriate stopping points.
  198.  *
  199.  * @see jack_set_buffer_size_callback()
  200.  *
  201.  * @param client pointer to JACK client structure.
  202.  * @param nframes new buffer size.  Must be a power of two.
  203.  *
  204.  * @return 0 on success, otherwise a non-zero error code
  205.  */
  206. int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes);
  207.  
  208. /**
  209.  * Tell JACK to call @a bufsize_callback whenever the size of the the
  210.  * buffer that will be passed to the @a process_callback is about to
  211.  * change.  Clients that depend on knowing the buffer size must supply
  212.  * a @a bufsize_callback before activating themselves.
  213.  *
  214.  * @param client pointer to JACK client structure.
  215.  * @param bufsize_callback function to call when the buffer size changes.
  216.  * @param arg argument for @a bufsize_callback.
  217.  *
  218.  * @return 0 on success, otherwise a non-zero error code
  219.  */
  220. int jack_set_buffer_size_callback (jack_client_t *client,
  221.                    JackBufferSizeCallback bufsize_callback,
  222.                    void *arg);
  223.  
  224. /**
  225.  * Tell the Jack server to call @a srate_callback whenever the system
  226.  * sample rate changes.
  227.  *
  228.  * @return 0 on success, otherwise a non-zero error code
  229.  */
  230. int jack_set_sample_rate_callback (jack_client_t *client,
  231.                    JackSampleRateCallback srate_callback,
  232.                    void *arg);
  233.  
  234. /**
  235.  * Tell the Jack server to call 'registration_callback' whenever a port is registered
  236.  * or unregistered, passing 'arg' as a second argument.
  237.  *
  238.  * @return 0 on success, otherwise a non-zero error code
  239.  */
  240. int jack_set_port_registration_callback (jack_client_t *,
  241.                      JackPortRegistrationCallback
  242.                      registration_callback, void *arg);
  243.  
  244. /**
  245.  * Tell the Jack server to call 'registration_callback' whenever the processing
  246.  * graph is reordered, passing 'arg' as an argument.
  247.  *
  248.  * @return 0 on success, otherwise a non-zero error code
  249.  */
  250. int jack_set_graph_order_callback (jack_client_t *, JackGraphOrderCallback graph_callback, void *);
  251.  
  252. /**
  253.  * Tell the Jack server to call 'xrun_callback' whenever there is a xrun, passing
  254.  * 'arg' as an argument.
  255.  *
  256.  * @return 0 on success, otherwise a non-zero error code
  257.  */
  258. int jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg);
  259.  
  260. /**
  261.  * Tell the Jack server that the program is ready to start processing
  262.  * audio.
  263.  *
  264.  * @return 0 on success, otherwise a non-zero error code
  265.  */
  266. int jack_activate (jack_client_t *client);
  267.  
  268. /**
  269.  * Tell the Jack server to remove this @a client from the process
  270.  * graph.  Also, disconnect all ports belonging to it, since inactive
  271.  * clients have no port connections.
  272.  *
  273.  * @return 0 on success, otherwise a non-zero error code
  274.  */
  275. int jack_deactivate (jack_client_t *client);
  276.  
  277. /**
  278.  * Create a new port for the client. This is an object used for moving
  279.  * data of any type in or out of the client.  Ports may be connected
  280.  * in various ways.
  281.  *
  282.  * Each port has a short name.  The port's full name contains the name
  283.  * of the client concatenated with a colon (:) followed by its short
  284.  * name.  The jack_port_name_size() is the maximum length of this full
  285.  * name.  Exceeding that will cause the port registration to fail and
  286.  * return NULL.
  287.  *
  288.  * All ports have a type, which may be any non-NULL and non-zero
  289.  * length string, passed as an argument.  Some port types are built
  290.  * into the JACK API, currently only JACK_DEFAULT_AUDIO_TYPE.
  291.  *
  292.  * @param client pointer to JACK client structure.
  293.  * @param port_name non-empty short name for the new port (not
  294.  * including the leading @a "client_name:").
  295.  * @param port_type port type name.  If longer than
  296.  * jack_port_type_size(), only that many characters are significant.
  297.  * @param flags @ref JackPortFlags bit mask.
  298.  * @param buffer_size must be non-zero if this is not a built-in @a
  299.  * port_type.  Otherwise, it is ignored.
  300.  *
  301.  * @return jack_port_t pointer on success, otherwise NULL.
  302.  */
  303. jack_port_t *jack_port_register (jack_client_t *client,
  304.                                  const char *port_name,
  305.                                  const char *port_type,
  306.                                  unsigned long flags,
  307.                                  unsigned long buffer_size);
  308.  
  309. /** 
  310.  * Remove the port from the client, disconnecting any existing
  311.  * connections.
  312.  *
  313.  * @return 0 on success, otherwise a non-zero error code
  314.  */
  315. int jack_port_unregister (jack_client_t *, jack_port_t *);
  316.  
  317. /**
  318.  * This returns a pointer to the memory area associated with the
  319.  * specified port. For an output port, it will be a memory area
  320.  * that can be written to; for an input port, it will be an area
  321.  * containing the data from the port's connection(s), or
  322.  * zero-filled. if there are multiple inbound connections, the data
  323.  * will be mixed appropriately.  
  324.  *
  325.  * FOR OUTPUT PORTS ONLY
  326.  * ---------------------
  327.  * You may cache the value returned, but only between calls to
  328.  * your "blocksize" callback. For this reason alone, you should
  329.  * either never cache the return value or ensure you have
  330.  * a "blocksize" callback and be sure to invalidate the cached
  331.  * address from there.
  332.  */
  333. void *jack_port_get_buffer (jack_port_t *, jack_nframes_t);
  334.  
  335. /**
  336.  * @return the full name of the jack_port_t (including the @a
  337.  * "client_name:" prefix).
  338.  *
  339.  * @see jack_port_name_size().
  340.  */
  341. const char *jack_port_name (const jack_port_t *port);
  342.  
  343. /**
  344.  * @return the short name of the jack_port_t (not including the @a
  345.  * "client_name:" prefix).
  346.  *
  347.  * @see jack_port_name_size().
  348.  */
  349. const char *jack_port_short_name (const jack_port_t *port);
  350.  
  351. /**
  352.  * @return the @ref JackPortFlags of the jack_port_t.
  353.  */
  354. int jack_port_flags (const jack_port_t *port);
  355.  
  356. /**
  357.  * @return the @a port type, at most jack_port_type_size() characters
  358.  * including a final NULL.
  359.  */
  360. const char *jack_port_type (const jack_port_t *port);
  361.  
  362. /** 
  363.  * @return TRUE if the jack_port_t belongs to the jack_client_t.
  364.  */
  365. int jack_port_is_mine (const jack_client_t *, const jack_port_t *port);
  366.  
  367. /** 
  368.  * @return number of connections to or from @a port.
  369.  *
  370.  * @pre The calling client must own @a port.
  371.  */
  372. int jack_port_connected (const jack_port_t *port);
  373.  
  374. /**
  375.  * @return TRUE if the locally-owned @a port is @b directly connected
  376.  * to the @a port_name.
  377.  *
  378.  * @see jack_port_name_size()
  379.  */
  380. int jack_port_connected_to (const jack_port_t *port,
  381.                 const char *port_name);
  382.  
  383. /**
  384.  * @return a null-terminated array of full port names to which the @a
  385.  * port is connected.  If none, returns NULL.
  386.  *
  387.  * The caller is responsible for calling free(3) on any non-NULL
  388.  * returned value.
  389.  *
  390.  * @param port locally owned jack_port_t pointer.
  391.  *
  392.  * @see jack_port_name_size(), jack_port_get_all_connections()
  393.  */   
  394. const char **jack_port_get_connections (const jack_port_t *port);
  395.  
  396. /**
  397.  * @return a null-terminated array of full port names to which the @a
  398.  * port is connected.  If none, returns NULL.
  399.  *
  400.  * The caller is responsible for calling free(3) on any non-NULL
  401.  * returned value.
  402.  *
  403.  * This differs from jack_port_get_connections() in two important
  404.  * respects:
  405.  *
  406.  *     1) You may not call this function from code that is
  407.  *          executed in response to a JACK event. For example,
  408.  *          you cannot use it in a GraphReordered handler.
  409.  *
  410.  *     2) You need not be the owner of the port to get information
  411.  *          about its connections. 
  412.  *
  413.  * @see jack_port_name_size()
  414.  */   
  415. const char **jack_port_get_all_connections (const jack_client_t *client,
  416.                         const jack_port_t *port);
  417.  
  418. /**
  419.  * A client may call this on a pair of its own ports to 
  420.  * semi-permanently wire them together. This means that
  421.  * a client that wants to direct-wire an input port to
  422.  * an output port can call this and then no longer
  423.  * have to worry about moving data between them. Any data
  424.  * arriving at the input port will appear automatically
  425.  * at the output port.
  426.  *
  427.  * The 'destination' port must be an output port. The 'source'
  428.  * port must be an input port. Both ports must belong to
  429.  * the same client. You cannot use this to tie ports between
  430.  * clients. That is what a connection is for.
  431.  *
  432.  * @return 0 on success, otherwise a non-zero error code
  433.  */
  434. int  jack_port_tie (jack_port_t *src, jack_port_t *dst);
  435.  
  436. /**
  437.  * This undoes the effect of jack_port_tie(). The port
  438.  * should be same as the 'destination' port passed to
  439.  * jack_port_tie().
  440.  *
  441.  * @return 0 on success, otherwise a non-zero error code
  442.  */
  443. int  jack_port_untie (jack_port_t *port);
  444.  
  445. /**
  446.  * A client may call this function to prevent other objects
  447.  * from changing the connection status of a port. The port
  448.  * must be owned by the calling client.
  449.  *
  450.  * @return 0 on success, otherwise a non-zero error code
  451.  */
  452. int jack_port_lock (jack_client_t *, jack_port_t *);
  453.  
  454. /**
  455.  * This allows other objects to change the connection status of a port.
  456.  *
  457.  * @return 0 on success, otherwise a non-zero error code
  458.  */
  459. int jack_port_unlock (jack_client_t *, jack_port_t *);
  460.  
  461. /** 
  462.  * @return the time (in frames) between data being available or
  463.  * delivered at/to a port, and the time at which it arrived at or is
  464.  * delivered to the "other side" of the port.  E.g. for a physical
  465.  * audio output port, this is the time between writing to the port and
  466.  * when the signal will leave the connector.  For a physical audio
  467.  * input port, this is the time between the sound arriving at the
  468.  * connector and the corresponding frames being readable from the
  469.  * port.
  470.  */
  471. jack_nframes_t jack_port_get_latency (jack_port_t *port);
  472.  
  473. /**
  474.  * The maximum of the sum of the latencies in every
  475.  * connection path that can be drawn between the port and other
  476.  * ports with the @ref JackPortIsTerminal flag set.
  477.  */
  478. jack_nframes_t jack_port_get_total_latency (jack_client_t *,
  479.                         jack_port_t *port);
  480.  
  481. /**
  482.  * The port latency is zero by default. Clients that control
  483.  * physical hardware with non-zero latency should call this
  484.  * to set the latency to its correct value. Note that the value
  485.  * should include any systemic latency present "outside" the
  486.  * physical hardware controlled by the client. For example,
  487.  * for a client controlling a digital audio interface connected
  488.  * to an external digital converter, the latency setting should
  489.  * include both buffering by the audio interface *and* the converter. 
  490.  */
  491. void jack_port_set_latency (jack_port_t *, jack_nframes_t);
  492.  
  493. /**
  494.  * Modify a port's short name.  May be called at any time.  If the
  495.  * resulting full name (including the @a "client_name:" prefix) is
  496.  * longer than jack_port_name_size(), it will be truncated.
  497.  *
  498.  * @return 0 on success, otherwise a non-zero error code.
  499.  */
  500. int jack_port_set_name (jack_port_t *port, const char *port_name);
  501.  
  502. /**
  503.  * If @ref JackPortCanMonitor is set for this @a port, turn input
  504.  * monitoring on or off.  Otherwise, do nothing.
  505.  */
  506. int jack_port_request_monitor (jack_port_t *port, int onoff);
  507.  
  508. /**
  509.  * If @ref JackPortCanMonitor is set for this @a port_name, turn input
  510.  * monitoring on or off.  Otherwise, do nothing.
  511.  *
  512.  * @return 0 on success, otherwise a non-zero error code.
  513.  *
  514.  * @see jack_port_name_size()
  515.  */
  516. int jack_port_request_monitor_by_name (jack_client_t *client,
  517.                        const char *port_name, int onoff);
  518.  
  519. /**
  520.  * If @ref JackPortCanMonitor is set for a port, this function turns
  521.  * on input monitoring if it was off, and turns it off if only one
  522.  * request has been made to turn it on.  Otherwise it does nothing.
  523.  *
  524.  * @return 0 on success, otherwise a non-zero error code
  525.  */
  526. int jack_port_ensure_monitor (jack_port_t *port, int onoff);
  527.  
  528. /**
  529.  * @return TRUE if input monitoring has been requested for @a port.
  530.  */
  531. int jack_port_monitoring_input (jack_port_t *port);
  532.  
  533. /**
  534.  * Establish a connection between two ports.
  535.  *
  536.  * When a connection exists, data written to the source port will
  537.  * be available to be read at the destination port.
  538.  *
  539.  * @pre The port types must be identical.
  540.  *
  541.  * @pre The @ref JackPortFlags of the @a source_port must include @ref
  542.  * JackPortIsOutput.
  543.  *
  544.  * @pre The @ref JackPortFlags of the @a destination_port must include
  545.  * @ref JackPortIsInput.
  546.  *
  547.  * @return 0 on success, EEXIST if the connection is already made,
  548.  * otherwise a non-zero error code
  549.  */
  550. int jack_connect (jack_client_t *,
  551.           const char *source_port,
  552.           const char *destination_port);
  553.  
  554. /**
  555.  * Remove a connection between two ports.
  556.  *
  557.  * @pre The port types must be identical.
  558.  *
  559.  * @pre The @ref JackPortFlags of the @a source_port must include @ref
  560.  * JackPortIsOutput.
  561.  *
  562.  * @pre The @ref JackPortFlags of the @a destination_port must include
  563.  * @ref JackPortIsInput.
  564.  *
  565.  * @return 0 on success, otherwise a non-zero error code
  566.  */
  567. int jack_disconnect (jack_client_t *,
  568.              const char *source_port,
  569.              const char *destination_port);
  570.  
  571. /**
  572.  * Perform the same function as jack_disconnect() using port handles
  573.  * rather than names.  This avoids the name lookup inherent in the
  574.  * name-based version.
  575.  *
  576.  * Clients connecting their own ports are likely to use this function,
  577.  * while generic connection clients (e.g. patchbays) would use
  578.  * jack_disconnect().
  579.  */
  580. int jack_port_disconnect (jack_client_t *, jack_port_t *);
  581.  
  582. /**
  583.  * @return the maximum number of characters in a full JACK port name
  584.  * including the final NULL character.  This value is a constant.
  585.  *
  586.  * A port's full name contains the owning client name concatenated
  587.  * with a colon (:) followed by its short name and a NULL
  588.  * character.
  589.  */
  590. int jack_port_name_size(void);
  591.  
  592. /**
  593.  * @return the maximum number of characters in a JACK port type name
  594.  * including the final NULL character.  This value is a constant.
  595.  */
  596. int jack_port_type_size(void);
  597.  
  598. /**
  599.  * @return the sample rate of the jack system, as set by the user when
  600.  * jackd was started.
  601.  */
  602. jack_nframes_t jack_get_sample_rate (jack_client_t *);
  603.  
  604. /**
  605.  * @return the current maximum size that will ever be passed to the @a
  606.  * process_callback.  It should only be used *before* the client has
  607.  * been activated.  This size may change, clients that depend on it
  608.  * must register a @a bufsize_callback so they will be notified if it
  609.  * does.
  610.  *
  611.  * @see jack_set_buffer_size_callback()
  612.  */
  613. jack_nframes_t jack_get_buffer_size (jack_client_t *);
  614.  
  615. /**
  616.  * @param port_name_pattern A regular expression used to select 
  617.  * ports by name.  If NULL or of zero length, no selection based 
  618.  * on name will be carried out.
  619.  * @param type_name_pattern A regular expression used to select 
  620.  * ports by type.  If NULL or of zero length, no selection based 
  621.  * on type will be carried out.
  622.  * @param flags A value used to select ports by their flags.  
  623.  * If zero, no selection based on flags will be carried out.
  624.  *
  625.  * @return a NULL-terminated array of ports that match the specified
  626.  * arguments.  The caller is responsible for calling free(3) any
  627.  * non-NULL returned value.
  628.  *
  629.  * @see jack_port_name_size(), jack_port_type_size()
  630.  */
  631. const char **jack_get_ports (jack_client_t *, 
  632.                  const char *port_name_pattern, 
  633.                  const char *type_name_pattern, 
  634.                  unsigned long flags);
  635.  
  636. /**
  637.  * @return address of the jack_port_t named @a port_name.
  638.  *
  639.  * @see jack_port_name_size()
  640.  */
  641. jack_port_t *jack_port_by_name (jack_client_t *, const char *port_name);
  642.  
  643. /**
  644.  * @return address of the jack_port_t of a @a port_id.
  645.  */
  646. jack_port_t *jack_port_by_id (const jack_client_t *client,
  647.                   jack_port_id_t port_id);
  648.  
  649. /**
  650.  * Old-style interface to become the timebase for the entire JACK
  651.  * subsystem.
  652.  *
  653.  * @deprecated This function still exists for compatibility with the
  654.  * earlier transport interface, but it does nothing.  Instead, see
  655.  * transport.h and use jack_set_timebase_callback().
  656.  *
  657.  * @return ENOSYS, function not implemented.
  658.  */
  659. int  jack_engine_takeover_timebase (jack_client_t *);
  660.  
  661. /**
  662.  * @return the time in frames that has passed since the JACK server
  663.  * began the current process cycle.
  664.  */
  665. jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *);
  666.  
  667. /**
  668.  * @return an estimate of the current time in frames.  This is a
  669.  * running counter, no significance should be attached to its value,
  670.  * but it can be compared to a previously returned value.
  671.  */
  672. jack_nframes_t jack_frame_time (const jack_client_t *);
  673.  
  674. /**
  675.  * @return the frame_time after the last processing of the graph
  676.  * this is only to be used from the process callback. 
  677.  *
  678.  * This function can be used to put timestamps generated by 
  679.  * jack_frame_time() in correlation to the current process cycle.
  680.  */
  681. jack_nframes_t jack_last_frame_time (const jack_client_t *client);
  682.  
  683.  
  684. /**
  685.  * @return the current CPU load estimated by JACK.  This is a running
  686.  * average of the time it takes to execute a full process cycle for
  687.  * all clients as a percentage of the real time available per cycle
  688.  * determined by the buffer size and sample rate.
  689.  */
  690. float jack_cpu_load (jack_client_t *client);
  691.  
  692. /**
  693.  * Set the directory in which the server is expected
  694.  * to have put its communication FIFOs. A client
  695.  * will need to call this before calling
  696.  * jack_client_new() if the server was started
  697.  * with arguments telling it to use a non-standard
  698.  * directory.
  699.  * 
  700.  * @deprecated This function is deprecated.  Don't use in new programs
  701.  * and remove it in old programs.
  702.  */
  703. void jack_set_server_dir (const char *path);
  704.  
  705. /**
  706.  * @return the pthread ID of the thread running the JACK client side
  707.  * code.
  708.  */
  709. pthread_t jack_client_thread_id (jack_client_t *);
  710.  
  711. /**
  712.  * Display JACK error message.
  713.  *
  714.  * Set via jack_set_error_function(), otherwise a JACK-provided
  715.  * default will print @a msg (plus a newline) to stderr.
  716.  *
  717.  * @param msg error message text (no newline at end).
  718.  */
  719. extern void (*jack_error_callback)(const char *msg);
  720.  
  721. /**
  722.  * Set the @ref jack_error_callback for error message display.
  723.  *
  724.  * The JACK library provides two built-in callbacks for this purpose:
  725.  * default_jack_error_callback() and silent_jack_error_callback().
  726.  */
  727. void jack_set_error_function (void (*func)(const char *));
  728.  
  729. #ifdef __cplusplus
  730. }
  731. #endif
  732.  
  733. #endif /* __jack_h__ */
  734.